home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 April: Mac OS SDK / Dev.CD Apr 99 SDK1.toast / Development Kits / Mac OS USB DDK / Mac OS USB DDK Readme < prev    next >
Encoding:
Text File  |  1999-02-15  |  16.2 KB  |  428 lines  |  [TEXT/ttxt]
  1.  ***
  2.  ***       Universal Serial Bus(tm) (USB) for the Mac OS
  3.  ***    Mac OS USB 1.2b2 DDK Developer Release Notes
  4.  ***    Copyright 1998 Apple Computer, Inc.
  5.  ***
  6.  
  7.  
  8.  Table of Contents:
  9. -------------------------------------------------------------
  10.  Changes from USB v1.0, 1.0.1, 1.1 -> v1.2b2
  11.  USB Fundamentals
  12.  Keeping up to date on Mac OS USB
  13.  Getting started with Mac OS USB
  14.  Installing the Mac OS USB Software
  15.  Using the Mac OS USB DDK under MPW
  16.  Using the Mac OS USB DDK with MetroWerks CodeWarrior
  17.  Installing the Mac OS USB DDK for CodeWarrior for the First Time  
  18.  Updating a Previously Installed Mac OS USB DDK for CodeWarrior
  19.  Using the CodeWarrior Project Files
  20.  Description of Installed Files
  21.  Known Problems and Issues
  22.  Contact Information
  23. -------------------------------------------------------------
  24.  
  25. Changes from USB v1.0, 1.0.1, 1.1 -> v1.2b2
  26. -------------------------------------------
  27.  
  28. Refer to the document "Mac OS USB v1.2b2 Readme" for a description
  29. of the changes between versions of USB.
  30.  
  31. System Requirements for USB 1.2b2
  32. ---------------------------------
  33.  
  34. Apple is formally qualifying USB 1.2b2 on iMac and Power Macintosh G3 systems
  35. with built-in USB support (and System 8.5.x installed).
  36.  
  37. USB Fundamentals
  38. ----------------
  39.  
  40. For the current generation of Power Macintosh systems, USB is the 
  41. primary interface for connections to low to medium speed peripheral
  42. devices. There are numerous advantages for adopting the USB standard on
  43. Macintosh, and they are discussed in the "Mac OS USB DDK API Reference
  44. Guide". On the future Macintosh systems there will be no ADB, 
  45. Serial Port, or SCSI connections. USB will be the primary port 
  46. for connecting peripheral devices to the Macintosh. 
  47.  
  48. The DDK provides the tools, interfaces, system files, and module 
  49. examples for you to start development of USB products
  50. for the Macintosh. The DDK provides the same release of USB
  51. component software that ships on the introductory release of the
  52. Power Macintosh iMac system.
  53.  
  54.  
  55. Keeping up to date on Mac OS USB
  56. --------------------------------
  57.  
  58. To stay abreast with developments on Mac OS USB, check out the 
  59. Mac OS USB Developer web site for the latest information. As updates
  60. to Mac OS USB occur, development releases of the software will be
  61. made available from this web site. The URL for the web site is:
  62.  
  63. <http://developer.apple.com/dev/usb>
  64.  
  65. You can also subscribe to the Mac OS USB Developer
  66. mailing list where development questions regarding Mac OS USB
  67. are posed and answered. To submit a question to the mailing list
  68. you must first be a subscriber. To subscribe to the mailing list,
  69. send an email with the subject field set to "subscribe" 
  70. (omit the double quotes for the message) to 
  71.  
  72. usb@isg.apple.com
  73.  
  74. USB Alerts to developers are always posted to the mailing list.
  75. These alerts are also posted to the Mac OS USB Developer Web
  76. site at the following location.
  77.  
  78. http://developer.apple.com/dev/usb/devalerts.html
  79.  
  80.  
  81. Getting started with Mac OS USB
  82. -------------------------------
  83.  
  84. To develop with Mac OS USB v1.1, you will need either an iMac or a Power
  85. Macintosh system with a USB PCI card installed.  For the iMac, you must
  86. have either System Software 8.5 present, or have installed at least the 
  87. iMac Update v1.0.
  88.  
  89. USB v1.1 will support PCI USB cards from several vendors, however the 
  90. Keyspan card has been extensively tested for compatibility with MacOS 
  91. 8.0, 8.1 & 8.5 and an the complete range of PCI-based Macintosh models.   
  92. This card includes USB v1.1 software on diskette, and Keyspan is prepared 
  93. to technical support to customers.
  94.  
  95.   http://www.keyspan.com/products/USB/
  96.  
  97. The enclosed software is for developmental purposes and will support USB 
  98. PCI cards from other vendors, but it is not directly supported by Apple, 
  99. nor is it intended for end-users. End-user customers are encouraged to 
  100. purchase a PCI USB card that includes licensed software and support.
  101.  
  102. You may find that development on a Power Mac system with a USB PCI card 
  103. and serial port, is easier, as you can use the Power Mac Debugger with a 
  104. second Power Macintosh system. A Power Macintosh system with ADB
  105. keyboard is useful for debugging with Macsbug, since there are cases when
  106. the system cannot process keystrokes from a USB keyboard.
  107.  
  108.  
  109. Installing the Mac OS USB Software
  110. ----------------------------------
  111.  
  112. Before using the enclosed software on an iMac, you must already have installed
  113. the iMac Update 1.0.
  114.  
  115. To install the USB System Software components, 
  116. 1. remove all files with the following names from your Extensions Folder, 
  117.  
  118.      USB Support,
  119.   USB Device Extension,
  120.   USBCompositeDriver,
  121.   USBFamilyExpert,
  122.   USBHIDKeyboardModule,
  123.   USBHIDMouseModule,
  124.   USBHIDUniversalModule,
  125.   USBHubDriver0,
  126.   USBHubDriver1, and
  127.   USBOpenHCIDriver
  128.  
  129. 2. drag copy the contents of the folder
  130.  
  131. :USBDDK:Extensions-AppleBuilt: 
  132.  
  133. to the Extensions folder.
  134.  
  135. 3. Before you reboot, modify the file "USB Support" to include
  136. a new resource 'usbx' (1984).  Without this resource, this release of
  137. USB will not load. The following alert is raised to indicate that the 
  138. resource is not present.
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152. 4. Reboot your system after making this modification.
  153.  
  154.  
  155. Important Notes on Installation and Use of this DDK software
  156. ------------------------------------------------------------
  157.  
  158. This DDK will let you look at the sources to some working class 
  159. drivers, build the examples, and develop & build your own code.
  160.  
  161. Please remember that these driver samples are Copyright Apple 
  162. Computer, Inc.. You may use the supplied code to develop Class 
  163. Drivers for your devices. As for publishing the source code, please
  164. check first with the Mac OS USB DDK License agreement, included
  165. in this DDK.
  166.  
  167. The current driver samples may, reflect the latest
  168. state of the art of driver writing for USB in the Mac OS. Note that
  169. the PrinterClassModule sample is for example
  170. purpose only. This sample is the basis for real
  171. drivers under development, however we are unable to provide
  172. the actual class driver code. The remaining examples are the
  173. real code for the Keyboard HID, Mouse HID, Universal HID, and 
  174. Composite class drivers which will ship on the iMac
  175.  
  176. While not extensively tested (by the development team), 
  177. the sample sources have been tweaked slightly to make builds 
  178. under CodeWarrior some what less problematic. The project files 
  179. are provided to help jumpstart your development process.
  180.  
  181.  
  182. Using the Mac OS USB DDK under MPW
  183. ----------------------------------
  184.  
  185. For previous releases of the USB DDK, we provided a current 
  186. UserStartup•USBDDK and makefiles for each of the sample class
  187. drivers. As there are very few developers who program
  188. with the MPW environment and to expidite the release of this 
  189. DDK, we will no provide make files for the class driver samples, 
  190. nor UserStartup files for MPW.
  191.  
  192. If MPW is your primary development platform and you need 
  193. a make file for one of the example class drivers, submit a 
  194. request to the Mac OS USB mailing list and a sample make file, if
  195. available for the example, will be sent to you. See the section
  196. "Keeping up to date on Mac OS USB" above for information on
  197. how to subscribe to the Mac OS USB Developer mailing list.
  198.  
  199.  
  200. Using the Mac OS USB DDK with MetroWerks CodeWarrior
  201. ---------------------------------------------------
  202.  
  203. We have supplied MetroWerks CodeWarrior project files for
  204. all of the USB Modules code examples. All of the project
  205. files were created using CodeWarrior Pro 1, IDE 2.0. The 
  206. project files are also compatible with CodeWarrior Pro IDE 
  207. 2.1, 3.0 and later.
  208.  
  209. For the CodeWarrior IDE environments v2.0 - v3.0, you must use
  210. the Universal Interface & Libraries v3.1. The examples will
  211. not build using the interfaces supplied with the CodeWarrior
  212. v.2 - v3.0 environments. The URL for the Developer Development
  213. Kits web page is
  214.    
  215.    <http://developer.apple.com/sdk/>
  216.  
  217. As mentioned for MPW, it is highly recommend that you use 
  218. one Macintosh for coding purposes and one Mac (aka "Target"
  219. system) for checkout/testing purposes.
  220.  
  221. The supplied project files will place the built drivers
  222. and extensions into the Target folder of the DDK.
  223.  
  224.  
  225. Installing the Mac OS USB DDK for CodeWarrior for the First Time
  226. -----------------------------------------------------------
  227.  
  228. 1. You can place the USBDDK anywhere on your development
  229.    system for the CodeWarrior environment. The access paths
  230.    for the project files are project and compiler relative.
  231.    If you move the examples folders out of the DDK, you must
  232.    fix the access paths so that the sources can be found.
  233.   
  234. 2. Ensure that the CodeWarrior IDE environment has at least the 
  235.    Universal Interfaces and Libraries 3.1 installed. The
  236.    download file from the DDK website includes instructions
  237.    for upgrading your CodeWarrior environment. Note that if
  238.    you upgrade your interfaces, you will also need to 
  239.    upgrade your precompiled headers. The supplied CodeWarrior
  240.    project files do not use precompiled headers.
  241.  
  242. 3. Copy the USB.h file included in this SDK to the 
  243.    ":Mac OS Support:Headers:Universal Headers:" folder.
  244.  
  245. 4. You will find that the project files will place the built drivers
  246.    and extensions into the folder.
  247.  
  248.     "USBDDK:Extensions-MCWBuilt"
  249.  
  250.    If this folder does not exist, or the folder name is different,
  251.    the class driver samples will be created in the CodeWarrior folder.
  252.  
  253. Updating a Previously Installed Mac OS USB DDK for CodeWarrior
  254. -------------------------------------------------------------
  255.  
  256. 1. Copy the USB.h file included in this SDK to the 
  257.    ":Mac OS Support:Headers:Universal Headers:" folder. Do not
  258.    use the USB.h header file from an earlier USB DDK with the
  259.    supplied project files, as the examples may not build.
  260.  
  261. 2. If you experience compiler errors with the program samples,
  262.    check whether you have updated the USB.h header in the
  263.    ":Mac OS Support:Headers:Universal Headers:" folder.
  264.  
  265. 3. You will need to create a folder by the name
  266.  
  267.     "USBDDK:Extensions-MCWBuilt"
  268.  
  269.    If this folder does not exist, or the folder name is different,
  270.    the class driver samples will be created in the CodeWarrior folder.
  271.  
  272. Using the CodeWarrior Project Files
  273. ---------------------------------
  274.  
  275.    For the following samples, there is only a single target for 
  276.    each project:
  277.  
  278.    CompositeClassDriver
  279.    KeyboardModule
  280.    MouseModule
  281.    UniversalModule
  282.    USBKeypad
  283.    USBModem
  284.    USBTabletModule
  285.  
  286.    For the PrinterClassDriver example, compile the targets in 
  287.    the following order
  288.  
  289.   1. PrinterClassDRVR - creates the 68K DRVR resource
  290.   2. PrintClassDriver - creates the USB PrintClassDriver module
  291.   3. ChooserPack.rsrc - creates the "PACK" resource
  292.   4. USB Chooser Driver - creates the Chooser extension for the 
  293.      USB printer
  294.    
  295.    For the USBSampleStorageDriver example, compile the targets in 
  296.    the following order
  297.  
  298.   1. USBStorageClassDriver - creates the USB StorageClassDriver module
  299.   2. USBStorageClassShim - creates the shim module which loads the unit
  300.                            table driver when the device is attached
  301.      USBStorageClassUTDriver - auto built into shim - native driver
  302.                            compiled as a resource into shim file.   
  303.    
  304. Description of Installed Files
  305. --------------------------
  306. Files in the 'Extensions-AppleBuilt' folder:
  307. Files:                  Description:
  308. USB Device Extension    File which contains the following class drivers
  309.                         USBCompositeDriver - A class driver which is loaded for class 0
  310.                              & and subclass 0 devices (typically keyboards & mice, 
  311.                              although a few    printers & modems appear as composite 
  312.                              class devices).
  313.                                              USBHubDriver0 & USBHubDriver1 - The Hub driver for the root hub,
  314.                              the Apple USB keyboard's hub, and most 3rd party hubs.
  315.                         USBKeyboardModule - The HID Module loaded for a keyboard 
  316.                              interface (typically in a compound device)
  317.                         USBMouseModule - A HID Module loaded for a mouse interface 
  318.                              (typically in a compound device).
  319.                         USBHIDUniversalModule - A HID Module designed to support a
  320.                              number of 3rd party gaming devices via Game Sprockets. 
  321.                              Refer to the "Mac OS USB Compatibility Notes" for a 
  322.                              description of the game devices supported.
  323.                         USBOpenHCIDriver - The HAL (Hardware Abstraction Layer), also 
  324.                              known as the "UIM" (USB Interface Module). This driver 
  325.                              provides an abstracted interface to the OpenHCI host 
  326.                              controllers on Mac motherboards and PCI controller cards.                      
  327.  
  328. USB Support             The INIT (actually an 'expt') portion of the Family 
  329.                         Expert. Loaded prior to the INIT parade, it starts 
  330.                         the 'find a USB bus (i.e. UIM driver), loads the
  331.                         hub driver (for the root hub), and starts
  332.                         the hub driver running.  Once running, the
  333.                         hub driver locates devices attached to the
  334.                         port and asks the FamilyExpertLib to load
  335.                         drivers for the devices connected to the
  336.                         hub's ports.                            
  337.                             
  338. USBPrintDriver          A Printing Class Driver for experimentation
  339.                         purposes.  Printing WILL NOT be functional
  340.                         simply with the addition of this file.  The
  341.                         chooser extension needed for USB printing
  342.                         is still in development and has not yet
  343.                         been released.
  344.           
  345.     
  346. Known Issues
  347. ------------
  348.  
  349. The following is a list of known issues with this final release
  350. of the USB DDK.
  351.  
  352.   - If you install this release of USB 1.1f3 directly without adding
  353.     the 'usbx' (1984) resource, then USB will not load and an
  354.     alert message is displayed
  355.  
  356.     Refer to the instructions above in section "Installing the Mac 
  357.     OS USB Software" on how to modify the "USB Support" file so that 
  358.     it will function correctly.
  359.  
  360.   - The USBSampleStorageDriver does not correctly demonstrate how to
  361.     handle a hot unplug situation. This sample will be updated to 
  362.     demonstrate how this situation should be properly handled. The 
  363.     existing sample sets up a Timer Task which when fired makes a
  364.     call to SystemTask.  The call to SystemTask is not supported
  365.     from an interrupt context.
  366.  
  367. Contact Information
  368. -------------------
  369.  
  370.   Mac OS USB DDK Upgrades and latest information:
  371.     
  372.     Check the Developer Development Kits web page for
  373.         upgrades to the Mac OS USB DDK. The web page is
  374.         
  375.         <http://developer.apple.com/sdk/>
  376.  
  377.     For the latest information on Mac OS USB, check the Mac OS USB web page.
  378.     The web page is
  379.  
  380.     <http://usb.apple.com>
  381.  
  382.   For Bug Reports:
  383.  
  384.     To ensure the appropriate data is collected, please use the Bug Reporter  
  385.     to send us your bug reports. The Bug Reporter can be found at: 
  386.  
  387.     <http://developer.apple.com/bugreporter>
  388.  
  389.     When reporting problems, please include the machine configuration, 
  390.     including the vendor of the PCI USB card which you have tested with.
  391.  
  392.   For Technical Questions:
  393.  
  394.                 For generic Mac OS USB questions, submit them to the Mac OS USB 
  395.     Developer mailing list. Refer to the section above "Keeping up to date 
  396.     on Mac OS USB" for information on how to subscribe to this mailing list.
  397.     Often questions can be answered by someone on the mailing list.
  398.  
  399.  
  400.                 If your question is not answered on the mailing list, or if your question 
  401.     is proprietary, contact Worldwide Developer with purchased development-level 
  402.     technical support incidents at
  403.  
  404.     dts@apple.com
  405.  
  406.     Technical support incidents are bundled in our Premier and Select 
  407.     Developer programs. For information about joining our programs, 
  408.     please visit our Apple Developer Connection web site at 
  409.  
  410.     http://developer.apple.com/programs. 
  411.  
  412.     If you have never purchased a technical support incident and would like 
  413.     to find out how to do so, please visit the following site: 
  414.  
  415.     http://developer.apple.com/programs/techsupport.html . 
  416.  
  417.     
  418.   Comments, Suggestions and Enhancement Requests
  419.  
  420.     Please send all comments and suggestions regarding the Mac OS USB DDK to
  421.     
  422.     usb@apple.com
  423.  
  424.     All email sent to this address will be read, however, we will not be to
  425.     respond to all of your comments and suggestions.
  426.  
  427.         
  428.